/*
    This file is part of libquickmail.

    libquickmail is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    libquickmail is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with libquickmail.  If not, see <http://www.gnu.org/licenses/>.

    Adapted for LUA-RTOS_ESP32 by Boris Lovosevic (loboris@gmail.com; https://github.com/loboris)
*/

/*! \file      quickmail.h
 *  \brief     header file for libquickmail
 *  \author    Brecht Sanders
 *  \date      2012-2016
 *  \copyright GPL
 */

#ifndef __INCLUDED_QUICKMAIL_H
#define __INCLUDED_QUICKMAIL_H

#include <stdio.h>

#ifdef __cplusplus
extern "C" {
#endif

#define QUICKMAIL_PROT_SMTP  1
#define QUICKMAIL_PROT_SMTPS 2


/*! \brief quickmail 对象类型 */
typedef struct email_info_struct* quickmail;



/*! \brief 用于打开附件数据的函数的指针类型
 * \param  filedata    传递给quickmail_add_body_custom / quickmail_add_attachment_custom的自定义数据
 * \return 调用quickmail_attachment_read_fn和quickmail_attachment_close_fn函数时使用的数据结构
 * \sa     quickmail_add_body_custom()
 * \sa     quickmail_add_attachment_custom()
 */
typedef void* (*quickmail_attachment_open_fn)(void* filedata);

/*! \brief 用于读取附件数据的函数的指针类型
 * \param  handle      data structure obtained via the corresponding quickmail_attachment_open_fn function
 * \param  buf         buffer for receiving data
 * \param  len         size in bytes of buffer for receiving data
 * \return number of bytes read (zero on end of file)
 * \sa     quickmail_add_body_custom()
 * \sa     quickmail_add_attachment_custom()
 */
typedef size_t (*quickmail_attachment_read_fn)(void* handle, void* buf, size_t len);

/*! \brief 用于关闭附件数据的函数的指针类型
 * \param  handle      data structure obtained via the corresponding quickmail_attachment_open_fn function
 * \sa     quickmail_add_body_custom()
 * \sa     quickmail_add_attachment_custom()
 */
typedef void (*quickmail_attachment_close_fn)(void* handle);

/*! \brief 指向quickmail_destroy中清理自定义数据的函数的指针类型
 * \param  filedata    custom data as passed to quickmail_add_body_custom/quickmail_add_attachment_custom
 * \sa     quickmail_add_body_custom()
 * \sa     quickmail_add_attachment_custom()
 */
typedef void (*quickmail_attachment_free_filedata_fn)(void* filedata);

/*! \brief 指向quickmail_destroy中清理自定义数据的函数的指针类型
 * \param  mailobj                        quickmail对象
 * \param  filename                       附件文件名 (与邮件正文的mimetype相同的值)
 * \param  mimetype                       MIME type
 * \param  attachment_data_open           打开附件数据的功能
 * \param  attachment_data_read           用于阅读附件数据的功能
 * \param  attachment_data_close          关闭附件数据的功能 (可选的, free() 将在NULL时使用)
 * \param  callbackdata                   自定义数据传递给quickmail_list_attachments
 * \sa     quickmail_list_bodies()
 * \sa     quickmail_list_attachments()
 */
typedef void (*quickmail_list_attachment_callback_fn)(quickmail mailobj, const char* filename, const char* mimetype, quickmail_attachment_open_fn email_info_attachment_open, quickmail_attachment_read_fn email_info_attachment_read, quickmail_attachment_close_fn email_info_attachment_close, void* callbackdata);



/*! \brief 获取版本的quickmail库
 * \return library version
 */
const char* quickmail_get_version ();

/*! \brief 清理quickmail库，在应用程序主线程结束时调用一次
 * \return 成功归零
 */
int quickmail_cleanup ();

/*! \brief 创建一个新的quickmail对象
 * \param  from        发件人电子邮件地址
 * \param  subject     电子邮件主题
 * \return quickmail对象或错误时为NULL
 */
quickmail quickmail_create (const char* from, const char* subject);

/*! \brief 清理一个quickmail对象
 * \param  mailobj    quickmail对象
 */
void quickmail_destroy (quickmail mailobj);

/*! \brief 设置quickmail对象的发件人（发件人）电子邮件地址
 * \param  mailobj     quickmail对象
 * \param  from        发件人电子邮件地址
 */
void quickmail_set_from (quickmail mailobj, const char* from);

/*! \brief 获取quickmail对象的发件人（来自）电子邮件地址
 * \param  mailobj     quickmail对象
 * \return 发件人电子邮件地址
 */
const char* quickmail_get_from (quickmail mailobj);

/*! \brief 将收件人（到）电子邮件地址添加到quickmail对象
 * \param  mailobj     quickmail对象
 * \param  e-mail      收件人的电子邮件地址
 */
void quickmail_add_to (quickmail mailobj, const char* email);

/*! \brief 将抄送收件人（cc）电子邮件地址添加到quickmail对象
 * \param  mailobj     quickmail对象
 * \param  e-mail      收件人的电子邮件地址
 */
void quickmail_add_cc (quickmail mailobj, const char* email);

/*! \brief 添加盲目抄送收件人（密送）电子邮件地址到quickmail对象
 * \param  mailobj     quickmail对象
 * \param  e-mail      recipient e-mail address
 */
void quickmail_add_bcc (quickmail mailobj, const char* email);

/*! \brief 设置一个quickmail对象的电子邮件主题
 * \param  mailobj     quickmail对象
 * \param  subject     电子邮件主题
 */
void quickmail_set_subject (quickmail mailobj, const char* subject);

/*! \brief 设置一个quickmail对象的电子邮件主题
 * \param  mailobj     quickmail对象
 * \return 电子邮件主题
 */
const char* quickmail_get_subject (quickmail mailobj);

/*! \brief 将电子邮件标题添加到quickmail对象
 * \param  mailobj     quickmail对象
 * \param  headerline  标题行添加
 */
void quickmail_add_header (quickmail mailobj, const char* headerline);

/*! \brief 设置一个quickmail对象的电子邮件主题
 * \param  mailobj     quickmail对象
 * \param  body        电子邮件正文
 */
void quickmail_set_body (quickmail mailobj, const char* body);

/*! \brief 设置一个quickmail对象的电子邮件主题
 * 将删除任何现有实体，并添加一个纯文本正文
 * \param  mailobj     quickmail对象
 * \return 电子邮件正文 or 出错时为NULL（调用者必须释放结果）
 */
char* quickmail_get_body (quickmail mailobj);

/*! \brief 将正文文件添加到quickmail对象（不建议使用）
 * \param  mailobj     quickmail对象
 * \param  mimetype    MIME type ( 如果设置为NULL，将使用 text/plain)
 * \param  path        文件的路径与身体数据
 */
void quickmail_add_body_file (quickmail mailobj, const char* mimetype, const char* path);

/*! \brief 从内存中添加一个body到一个quickmail对象
 * \param  mailobj     quickmail对象
 * \param  mimetype    MIME type (text/plain will be used if set to NULL)
 * \param  data        body content
 * \param  datalen     size of data in bytes
 * \param  mustfree    non-zero if data must be freed by quickmail_destroy
 */
void quickmail_add_body_memory (quickmail mailobj, const char* mimetype, char* data, size_t datalen, int mustfree);

/*! \brief 添加具有自定义读取函数的正文到quickmail对象
 * \param  mailobj                        quickmail对象
 * \param  mimetype                       MIME type (text/plain will be used if set to NULL)
 * \param  data                           custom data passed to attachment_data_open and attachment_data_filedata_free functions
 * \param  attachment_data_open           function for opening attachment data
 * \param  attachment_data_read           function for reading attachment data
 * \param  attachment_data_close          function for closing attachment data (optional, free() will be used if NULL)
 * \param  attachment_data_filedata_free  function for cleaning up custom data in quickmail_destroy (optional, free() will be used if NULL)
 */
void quickmail_add_body_custom (quickmail mailobj, const char* mimetype, char* data, quickmail_attachment_open_fn attachment_data_open, quickmail_attachment_read_fn attachment_data_read, quickmail_attachment_close_fn attachment_data_close, quickmail_attachment_free_filedata_fn attachment_data_filedata_free);

/*! \brief 从quickmail对象中删除body
 * \param  mailobj     quickmail对象
 * \param  mimetype    MIME类型（如果设置为NULL，将使用text / plain）
 * \return 成功归零
 */
int quickmail_remove_body (quickmail mailobj, const char* mimetype);

/*! \brief 通过为每个主体调用回调函数来列出主体
 * \param  mailobj                        quickmail对象
 * \param  callback                       调用每个附件的功能
 * \param  callbackdata                   要传递给回调函数的自定义数据
 * \sa     quickmail_list_attachment_callback_fn
 */
void quickmail_list_bodies (quickmail mailobj, quickmail_list_attachment_callback_fn callback, void* callbackdata);

/*! \brief 将文件附件添加到quickmail对象
 * \param  mailobj     quickmail对象
 * \param  path        要附加的文件的路径
 * \param  mimetype    要附加的MIME类型（如果设置为NULL，将使用application / octet-stream）
 */
void quickmail_add_attachment_file (quickmail mailobj, const char* path, const char* mimetype);

/*! \brief 从内存中添加附件到quickmail对象
 * \param  mailobj     quickmail对象
 * \param  filename    要附加的文件的名称（不得包含完整路径）
 * \param  mimetype    要附加的MIME类型（默认二进制文件设置为NULL）
 * \param  data        数据内容
 * \param  datalen     以字节为单位的数据大小
 * \param  mustfree    如果必须通过quickmail_destroy释放数据，则为非零
 */
void quickmail_add_attachment_memory (quickmail mailobj, const char* filename, const char* mimetype, char* data, size_t datalen, int mustfree);

/*! \brief 将具有自定义读取功能的附件添加到quickmail对象
 * \param  mailobj                        quickmail对象
 * \param  filename                       name of file to attach (must not include full path)
 * \param  mimetype                       MIME type of file to attach (set to NULL for default binary file)
 * \param  data                           custom data passed to attachment_data_open and attachment_data_filedata_free functions
 * \param  attachment_data_open           function for opening attachment data
 * \param  attachment_data_read           function for reading attachment data
 * \param  attachment_data_close          function for closing attachment data (optional, free() will be used if NULL)
 * \param  attachment_data_filedata_free  function for cleaning up custom data in quickmail_destroy (optional, free() will be used if NULL)
 */
void quickmail_add_attachment_custom (quickmail mailobj, const char* filename, const char* mimetype, char* data, quickmail_attachment_open_fn attachment_data_open, quickmail_attachment_read_fn attachment_data_read, quickmail_attachment_close_fn attachment_data_close, quickmail_attachment_free_filedata_fn attachment_data_filedata_free);

/*! \brief 从quickmail对象中删除附件
 * \param  mailobj     quickmail对象
 * \param  filename    name of file to attach (must not include full path)
 * \return zero on success
 */
int quickmail_remove_attachment (quickmail mailobj, const char* filename);

/*! \brief 通过为每个附件调用回调函数来列出附件
 * \param  mailobj                        quickmail对象
 * \param  callback                       function to call for each attachment
 * \param  callbackdata                   custom data to pass to the callback function
 * \sa     quickmail_list_attachment_callback_fn
 */
void quickmail_list_attachments (quickmail mailobj, quickmail_list_attachment_callback_fn callback, void* callbackdata);

/*! \brief 设置quickmail对象的调试日志目标
 * \param  mailobj     quickmail对象
 * \param  filehandle  记录目标的文件句柄（或没有记录的NULL）
 */
void quickmail_set_debug_log (quickmail mailobj, FILE* filehandle);

/*! \brief 将生成的电子邮件保存到文件中
 * \param  mailobj     quickmail对象
 * \param  filehandle  用于将电子邮件内容写入的文件句柄
 */
void quickmail_fsave (quickmail mailobj, FILE* filehandle);

/*! \brief 从电子邮件内容中读取数据的下一个数据（可以用作CURLOPT_READFUNCTION回调函数）
 * \param  buffer      缓冲区将数据复制到（胸围可以容纳大小* nmemb字节）
 * \param  size        记录大小
 * \param  nmemb       要复制到\ p buffer的记录数
 * \param  mailobj     quickmail对象
 * \return 复制到\ p buffer的字节数，如果是，则复制为0
 */
size_t quickmail_get_data (void* buffer, size_t size, size_t nmemb, void* mailobj);


//3种邮件发送模式，smtp、smtps、协议模式（smtp或smtps）

/*! \brief 通过SMTP或SMTPS发送电子邮件
 * \param  mailobj     quickmail对象
 * \param  smtpserver  SMTP / SMTPS服务器的IP地址或主机名
 * \param  smtpport    SMTP / SMTPS端口号（通常为25）
 * \param  prptocol    协议类型（SMTP或SMTPS）
 * \param  username    用于身份验证的用户名（如果不需要，则为NULL）
 * \param  password    用于身份验证的密码（如果不需要，则为NULL）
 * \return 成功时为NULL或错误时出现错误消息
 */
const char* quickmail_protocol_send (quickmail mailobj, const char* smtpserver, unsigned int smtpport, int protocol, const char* username, const char* password);

/*! \brief 通过SMTP发送电子邮件
 * \param  mailobj     quickmail对象
 * \param  smtpserver  SMTP服务器的IP地址或主机名
 * \param  smtpport    SMTP端口号（通常为25）
 * \param  username    用于身份验证的用户名（如果不需要，则为NULL）
 * \param  password    用于身份验证的密码（如果不需要，则为NULL）
 * \return 成功时为NULL或错误时出现错误消息
 */
const char* quickmail_send (quickmail mailobj, const char* smtpserver, unsigned int smtpport, const char* username, const char* password);

/*! \brief 通过SMTPS发送电子邮件
 * \param  mailobj     quickmail对象
 * \param  smtpserver  SMTPS服务器的IP地址或主机名
 * \param  smtpport    SMTPS端口号（通常为465）
 * \param  username    用于身份验证的用户名（如果不需要，则为NULL）
 * \param  password    用于身份验证的密码（如果不需要，则为NULL）
 * \return 成功时为NULL 或 错误时出现错误消息
 */
const char* quickmail_send_secure (quickmail mailobj, const char* smtpserver, unsigned int smtpport, const char* username, const char* password);

int quickmail_progress;
int quickmail_verbose;
int quickmail_timeout;

#ifdef __cplusplus
}
#endif

#endif //__INCLUDED_QUICKMAIL_H
